<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: ipc::transport::struc::Heap_fixed_builder_capnp_message_builder Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceipc.html">ipc</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1transport.html">transport</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1transport_1_1struc.html">struc</a></li><li class="navelem"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html">Heap_fixed_builder_capnp_message_builder</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="#pri-attribs">Private Attributes</a> &#124;
<a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder-members.html">List of all members</a>  </div>
  <div class="headertitle"><div class="title">ipc::transport::struc::Heap_fixed_builder_capnp_message_builder Class Reference</div></div>
</div><!--header-->
<div class="contents">

<p>A <code>capnp::MessageBuilder</code> used by <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder.html" title="Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in th...">Heap_fixed_builder</a>: similar to a <code>capnp::MallocMessageBuilder</code> with the FIXED_SIZE alloc-strategy but with framing space around the allocated segment(s).  
 <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#details">More...</a></p>

<p><code>#include &lt;<a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html">heap_fixed_builder_capnp_msg_builder.hpp</a>&gt;</code></p>
<div class="dynheader">
Inheritance diagram for ipc::transport::struc::Heap_fixed_builder_capnp_message_builder:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder__inherit__graph.svg" width="194" height="131"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<div class="dynheader">
Collaboration diagram for ipc::transport::struc::Heap_fixed_builder_capnp_message_builder:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder__coll__graph.svg" width="787" height="222"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-methods" name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a29e45b9263096e876754ea544031242d"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a29e45b9263096e876754ea544031242d">Heap_fixed_builder_capnp_message_builder</a> (flow::log::Logger *logger_for_blobs, size_t segment_sz, size_t frame_prefix_sz, size_t frame_postfix_sz)</td></tr>
<tr class="memdesc:a29e45b9263096e876754ea544031242d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Constructs the message-builder, with the policy to allocate the segments in a particular way, always with a fixed size.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a29e45b9263096e876754ea544031242d">More...</a><br /></td></tr>
<tr class="separator:a29e45b9263096e876754ea544031242d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a478c109e008dd33b04b605278c1b2a54"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54">emit_segment_blobs</a> (<a class="el" href="namespaceipc_1_1transport_1_1struc.html#a82a69eaa39cbe8a002de1266f1cbb5cb">Segment_ptrs</a> *target_blob_ptrs)</td></tr>
<tr class="memdesc:a478c109e008dd33b04b605278c1b2a54"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns pointers to <code>Blob</code>s which are the serialization segments at this time.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54">More...</a><br /></td></tr>
<tr class="separator:a478c109e008dd33b04b605278c1b2a54"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8d4767193250d909cdf5b298f92f43e9"><td class="memItemLeft" align="right" valign="top">size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a8d4767193250d909cdf5b298f92f43e9">n_segments</a> () const</td></tr>
<tr class="memdesc:a8d4767193250d909cdf5b298f92f43e9"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns what <code>target_blob_ptrs.size()</code> would return after calling <code>emit_segment_blobs(&amp;target_blob_ptrs)</code> (with an empty <code>target_blob_ptrs</code> going-in), right now.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a8d4767193250d909cdf5b298f92f43e9">More...</a><br /></td></tr>
<tr class="separator:a8d4767193250d909cdf5b298f92f43e9"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a766736906354f28d6ef2fa0752ba0e21"><td class="memItemLeft" align="right" valign="top">kj::ArrayPtr&lt;::capnp::word &gt;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a766736906354f28d6ef2fa0752ba0e21">allocateSegment</a> (unsigned int min_sz) override</td></tr>
<tr class="memdesc:a766736906354f28d6ef2fa0752ba0e21"><td class="mdescLeft">&#160;</td><td class="mdescRight">Implements <code>MessageBuilder</code> API.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a766736906354f28d6ef2fa0752ba0e21">More...</a><br /></td></tr>
<tr class="separator:a766736906354f28d6ef2fa0752ba0e21"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pri-attribs" name="pri-attribs"></a>
Private Attributes</h2></td></tr>
<tr class="memitem:ae15044026ef19363177d474c6ac890bc"><td class="memItemLeft" align="right" valign="top">flow::log::Logger *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#ae15044026ef19363177d474c6ac890bc">m_logger_for_blobs</a></td></tr>
<tr class="memdesc:ae15044026ef19363177d474c6ac890bc"><td class="mdescLeft">&#160;</td><td class="mdescRight">See ctor.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#ae15044026ef19363177d474c6ac890bc">More...</a><br /></td></tr>
<tr class="separator:ae15044026ef19363177d474c6ac890bc"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:af012d6917cdc16494a22b4b6f2c10edd"><td class="memItemLeft" align="right" valign="top">const size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#af012d6917cdc16494a22b4b6f2c10edd">m_segment_sz</a></td></tr>
<tr class="memdesc:af012d6917cdc16494a22b4b6f2c10edd"><td class="mdescLeft">&#160;</td><td class="mdescRight">See ctor.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#af012d6917cdc16494a22b4b6f2c10edd">More...</a><br /></td></tr>
<tr class="separator:af012d6917cdc16494a22b4b6f2c10edd"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ac4e465bb2099093f06cd7e969d2e3de6"><td class="memItemLeft" align="right" valign="top">const size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#ac4e465bb2099093f06cd7e969d2e3de6">m_frame_prefix_sz</a></td></tr>
<tr class="memdesc:ac4e465bb2099093f06cd7e969d2e3de6"><td class="mdescLeft">&#160;</td><td class="mdescRight">See ctor.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#ac4e465bb2099093f06cd7e969d2e3de6">More...</a><br /></td></tr>
<tr class="separator:ac4e465bb2099093f06cd7e969d2e3de6"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aa52369c664ada39cedb0a70f08880931"><td class="memItemLeft" align="right" valign="top">const size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#aa52369c664ada39cedb0a70f08880931">m_frame_postfix_sz</a></td></tr>
<tr class="memdesc:aa52369c664ada39cedb0a70f08880931"><td class="mdescLeft">&#160;</td><td class="mdescRight">See ctor.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#aa52369c664ada39cedb0a70f08880931">More...</a><br /></td></tr>
<tr class="separator:aa52369c664ada39cedb0a70f08880931"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aad029fd4e08580a785824c48790c748f"><td class="memItemLeft" align="right" valign="top">std::vector&lt; boost::movelib::unique_ptr&lt; flow::util::Blob &gt; &gt;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#aad029fd4e08580a785824c48790c748f">m_serialization_segments_plus_frame_space</a></td></tr>
<tr class="memdesc:aad029fd4e08580a785824c48790c748f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Before <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a>, stores each segment allocated as requested by capnp via <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a766736906354f28d6ef2fa0752ba0e21" title="Implements MessageBuilder API.">allocateSegment()</a> <code>virtual</code> API, with <code>.size()</code> equal to <code>.capacity()</code> and &gt;= <code>min_sz</code> (arg to that method); immediately after <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a> each <code>.size()</code> is adjusted to indicate the # of bytes actually used in that segment in the final serialization.  <a href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#aad029fd4e08580a785824c48790c748f">More...</a><br /></td></tr>
<tr class="separator:aad029fd4e08580a785824c48790c748f"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p >A <code>capnp::MessageBuilder</code> used by <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder.html" title="Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in th...">Heap_fixed_builder</a>: similar to a <code>capnp::MallocMessageBuilder</code> with the FIXED_SIZE alloc-strategy but with framing space around the allocated segment(s). </p>
<p >It can also be used as a <a class="el" href="classCapnp__msg__builder__interface.html">Capnp_msg_builder_interface</a> (<code>capnp::MessageBuilder</code>) independently of the rest of <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a> or even <a class="el" href="namespaceipc.html" title="Catch-all namespace for the Flow-IPC project: A library/API in modern C++17 providing high-performanc...">ipc</a>, although that was not the impetus for its development.</p>
<h3>Move-ctible and move-assignable</h3>
<p >Super-class <a class="el" href="classCapnp__msg__builder__interface.html">Capnp_msg_builder_interface</a>, which is an abstract class but not a pure interface (it has data and concrete methods), is move-ctible and move-assignable (but not copyable). Accordingly, the present class is as well. (So is our peer <code>capnp::MallocMessageBuilder</code>.) However: as of this writing (newest version capnp 0.10) <a class="el" href="classCapnp__msg__builder__interface.html">Capnp_msg_builder_interface</a> consists of a raw data area that = 1 <code>bool</code> + 22 words; or at least 176 bytes in a 64-bit system. Its (defaulted) move ctor/assignment will thus need to copy the 176+ bytes. That is a little "fat." We add another 3 <code>size_t</code>, a pointer, and a <code>vector</code> of 1+ pointers, or 30+ bytes. Hence the user may wish to wrap us in a <code>unique_ptr</code>, and only then use the move semantics; as the trade-off against the extra alloc/dealloc is arguably worth it. The same arguably holds for any <a class="el" href="classCapnp__msg__builder__interface.html">Capnp_msg_builder_interface</a> sub-class (interface implementation).</p>
<p >Style note: Much of the rest of the code explicitly documents deleted copy-ctor/assignment and defaulted move-ctor/assignment (as separate items each with a doc header); we do not. This is of course for brevity; but we justify it in that the abstract class (interface) we implement (<a class="el" href="classCapnp__msg__builder__interface.html">Capnp_msg_builder_interface</a>) omits them as well.</p>
<h3>Rationale</h3>
<p >Why we'd use a <code>MallocMessageBuilder</code>-like approach is explained within <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder.html" title="Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in th...">Heap_fixed_builder</a> doc header. So why not just use that actual class? Answer: We send the resulting serialization segments over IPC pipes (<a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Blob_sender</a>, <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a>), and in some cases <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a> needs to surround the serialization with a bit of metadata. <code>MallocMessageBuilder</code> will, for each segment, allocate X bytes &ndash; and then potentially fill all of them. The only way for <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a> to work with this is to allocate another buffer of X + (frame size) bytes and then copy the X bytes into it &ndash; losing the adherence to the zero-copy-when-possible paradigm. Hence this class which will use <code>flow::util::Blob</code> machinery to maintain the frame space.</p>
<p >(Update: The previous paragraph remains correct in that in order to support the framing feature it was necessary to write this class, as <code>MallocMessageBuilder</code> does not have it. However <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a> no longer needs to frame "a bit of metadata" around the serialization; hence it does not require this framing feature; hence we could now get rid of the present class and just use <code>MallocMessageBuilder</code>. Nevertheless I (ygoldfel) have kept this class around, as it is a nice feature in general. Plus niceties like <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a> and <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a8d4767193250d909cdf5b298f92f43e9" title="Returns what target_blob_ptrs.size() would return after calling emit_segment_blobs(&amp;target_blob_ptrs)...">n_segments()</a> remain nice.)</p>
<p >Note that in order to make use of the added feature (frame space) one should <em>not</em> access the serialization result via the usual <code>MessageBuilder::getSegmentsForOutput()</code>. That still works, and that method is essential in the impl of this class; but it returns only the actual serialization segments (each one's start and size, not including for example the allocated-but-unused data probably at the tail of the allocated buffer). Technically it would indeed be correct/safe to simply write frame prefix data by subtracting <code>frame_prefix_sz</code> from the segment's start pointer and writing there; and similarly write postfix data immediately past the end of the start ptr + size. However that is error-prone and inconvenient. Call <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a> instead: it will return the <code>flow::util::Blob</code>s which will have set <code>start()</code> and <code>size()</code> appropriately (see <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a> doc header). </p>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00084">84</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html">heap_fixed_builder_capnp_msg_builder.hpp</a>.</p>
</div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="a29e45b9263096e876754ea544031242d" name="a29e45b9263096e876754ea544031242d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a29e45b9263096e876754ea544031242d">&#9670;&nbsp;</a></span>Heap_fixed_builder_capnp_message_builder()</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::Heap_fixed_builder_capnp_message_builder </td>
          <td>(</td>
          <td class="paramtype">flow::log::Logger *&#160;</td>
          <td class="paramname"><em>logger_for_blobs</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>segment_sz</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>frame_prefix_sz</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>frame_postfix_sz</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">explicit</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Constructs the message-builder, with the policy to allocate the segments in a particular way, always with a fixed size. </p>
<p >Namely, capnp will call <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a766736906354f28d6ef2fa0752ba0e21" title="Implements MessageBuilder API.">allocateSegment()</a> with <code>min_sz * sizeof(word) == M</code>. This will:</p><ul>
<li>Create an internal <code>flow::util::Blob B</code> with:<ul>
<li><code>capacity()</code> = <code>max(M, segment_sz) + frame_prefix_sz + frame_postfix_sz</code>, up to ceiling-nearest word;</li>
<li><code>start()</code> = <code>frame_prefix_sz</code>.</li>
<li><code>size()</code> = <code>capacity() - start() - frame_postfix_sz</code> which equals ~<code>max(M, segment_sz)</code>.</li>
</ul>
</li>
<li>Return <code>ArrayPtr</code> pointing at <code>B.begin()</code> (which is buffer start + <code>start()</code>), sized <code>B.size()</code> (that is, <code>max(M, segment_sz)</code> adjust to ceiling-nearest word).</li>
</ul>
<p >Furthermore, this will cause the following <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a> behavior:</p><ul>
<li>It will emit a sequence of <code>flow::util::Blob</code> pointers to the above.</li>
<li>Each <code>Blob</code> pointer will correspond to an earlier <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a766736906354f28d6ef2fa0752ba0e21" title="Implements MessageBuilder API.">allocateSegment()</a> call 1-1.</li>
<li>The pointee's <code>start()</code> will be as above.</li>
<li>The pointee's <code>size()</code> will equal the serialization segment's size as determined ultimately by capnp (per <code>getSegmentsForOutput()</code>). This will be at most <code>max(M, segment_sz)</code> (less if it didn't need every single byte to hold the serialization ultimately &ndash; it is typical some bytes are wasted).</li>
<li>Its <code>capacity() - start() - size() &gt;= frame_postfix_sz</code>.</li>
</ul>
<p >In this way the consumer of <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a> (presumably <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a>) will be able to adjust <code>start()</code> and <code>size()</code> of each serialization <code>Blob</code> to add framing info if needed.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">logger_for_blobs</td><td>Passed to each <code>Blob</code> ctor. </td></tr>
    <tr><td class="paramname">segment_sz</td><td>See above. </td></tr>
    <tr><td class="paramname">frame_prefix_sz</td><td>Guaranteed space for prefix framing. See above. This must be a multiple of <code>sizeof(void*)</code>; else behavior undefined (assertion may trip). </td></tr>
    <tr><td class="paramname">frame_postfix_sz</td><td>Guaranteed space for postfix framing. See above. </td></tr>
  </table>
  </dd>
</dl>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00034">34</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html">heap_fixed_builder_capnp_msg_builder.cpp</a>.</p>

</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a id="a766736906354f28d6ef2fa0752ba0e21" name="a766736906354f28d6ef2fa0752ba0e21"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a766736906354f28d6ef2fa0752ba0e21">&#9670;&nbsp;</a></span>allocateSegment()</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">kj::ArrayPtr&lt; capnp::word &gt; ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::allocateSegment </td>
          <td>(</td>
          <td class="paramtype">unsigned int&#160;</td>
          <td class="paramname"><em>min_sz</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">override</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Implements <code>MessageBuilder</code> API. </p>
<p >Invoked by capnp, as the user mutates via <code>Builder</code>s. Do not invoke directly.</p>
<dl class="section note"><dt>Note</dt><dd>The strange capitalization (that goes against standard Flow-IPC style) is because we are implementing a capnp API.</dd></dl>
<p>For details as to how this will behave in context of <code>*this</code> see <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a29e45b9263096e876754ea544031242d" title="Constructs the message-builder, with the policy to allocate the segments in a particular way,...">Heap_fixed_builder_capnp_message_builder()</a> ctor doc header.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">min_sz</td><td>See <code>MessageBuilder</code> API. The allocated segment will allow for a serialization of at most <code>min(min_sz * sizeof(word), segment_sz)</code> bytes, where <code>segment_sz</code> was passed to ctor (adjusted to the ceiling-nearest word). </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>See <code>MessageBuilder</code> API. The ptr and size of the area for capnp to serialize-to. (As noted in ctor doc header: <code>frame_prefix_sz</code> bytes will precede this area, and <code>frame_postfix_sz</code> will succeed it.) </dd></dl>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00086">86</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html">heap_fixed_builder_capnp_msg_builder.cpp</a>.</p>

<p class="reference">References <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00189">m_frame_postfix_sz</a>, <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00187">m_frame_prefix_sz</a>, <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00183">m_logger_for_blobs</a>, <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00185">m_segment_sz</a>, and <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00199">m_serialization_segments_plus_frame_space</a>.</p>

</div>
</div>
<a id="a478c109e008dd33b04b605278c1b2a54" name="a478c109e008dd33b04b605278c1b2a54"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a478c109e008dd33b04b605278c1b2a54">&#9670;&nbsp;</a></span>emit_segment_blobs()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::emit_segment_blobs </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1transport_1_1struc.html#a82a69eaa39cbe8a002de1266f1cbb5cb">Segment_ptrs</a> *&#160;</td>
          <td class="paramname"><em>target_blob_ptrs</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Returns pointers to <code>Blob</code>s which are the serialization segments at this time. </p>
<p >They are as follows:</p><ul>
<li>Each <code>Blob</code> holds a serialization segment, in order. There shall be at least 1.</li>
<li>For each <code>Blob B</code> (see ctor):<ul>
<li><code>start() == frame_prefix_sz</code>.</li>
<li><code>capacity() - start() - size() &gt;= frame_postfix_sz</code>.</li>
<li>[<code>begin()</code>, <code>end()</code>) is the serialization segment. Recall that <code>begin()</code> starts at position <code>start()</code>, while <code>end()</code> is at position <code>start() + size()</code>.</li>
</ul>
</li>
</ul>
<p >Therefore one can use <code>B.resize()</code> and similar and then add frame data without breaking zero-copy.</p>
<p >This method can be invoked more than once; however the emitted result is meaningless once any mutation occurs subsequently.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">target_blob_ptrs</td><td>It is appended-to. Recall these are mere pointers (into <code>*this</code>-managed heap memory). </td></tr>
  </table>
  </dd>
</dl>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00042">42</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html">heap_fixed_builder_capnp_msg_builder.cpp</a>.</p>

<p class="reference">References <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00189">m_frame_postfix_sz</a>, <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00187">m_frame_prefix_sz</a>, <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00199">m_serialization_segments_plus_frame_space</a>, and <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00135">n_segments()</a>.</p>
<div class="dynheader">
Here is the call graph for this function:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder_a478c109e008dd33b04b605278c1b2a54_cgraph.svg" width="376" height="71"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
</div>

</div>
</div>
<a id="a8d4767193250d909cdf5b298f92f43e9" name="a8d4767193250d909cdf5b298f92f43e9"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8d4767193250d909cdf5b298f92f43e9">&#9670;&nbsp;</a></span>n_segments()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">size_t ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::n_segments </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td> const</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Returns what <code>target_blob_ptrs.size()</code> would return after calling <code>emit_segment_blobs(&amp;target_blob_ptrs)</code> (with an empty <code>target_blob_ptrs</code> going-in), right now. </p>
<p >In other words it is the number of times capnp has invoked <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a766736906354f28d6ef2fa0752ba0e21" title="Implements MessageBuilder API.">allocateSegment()</a>.</p>
<dl class="section return"><dt>Returns</dt><dd>See above. </dd></dl>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00135">135</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html">heap_fixed_builder_capnp_msg_builder.cpp</a>.</p>

<p class="reference">References <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00199">m_serialization_segments_plus_frame_space</a>.</p>

<p class="reference">Referenced by <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00042">emit_segment_blobs()</a>.</p>
<div class="dynheader">
Here is the caller graph for this function:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder_a8d4767193250d909cdf5b298f92f43e9_icgraph.svg" width="376" height="71"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
</div>

</div>
</div>
<h2 class="groupheader">Member Data Documentation</h2>
<a id="aa52369c664ada39cedb0a70f08880931" name="aa52369c664ada39cedb0a70f08880931"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa52369c664ada39cedb0a70f08880931">&#9670;&nbsp;</a></span>m_frame_postfix_sz</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">const size_t ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::m_frame_postfix_sz</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">private</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>See ctor. </p>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00189">189</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html">heap_fixed_builder_capnp_msg_builder.hpp</a>.</p>

<p class="reference">Referenced by <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00086">allocateSegment()</a>, and <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00042">emit_segment_blobs()</a>.</p>

</div>
</div>
<a id="ac4e465bb2099093f06cd7e969d2e3de6" name="ac4e465bb2099093f06cd7e969d2e3de6"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac4e465bb2099093f06cd7e969d2e3de6">&#9670;&nbsp;</a></span>m_frame_prefix_sz</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">const size_t ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::m_frame_prefix_sz</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">private</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>See ctor. </p>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00187">187</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html">heap_fixed_builder_capnp_msg_builder.hpp</a>.</p>

<p class="reference">Referenced by <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00086">allocateSegment()</a>, and <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00042">emit_segment_blobs()</a>.</p>

</div>
</div>
<a id="ae15044026ef19363177d474c6ac890bc" name="ae15044026ef19363177d474c6ac890bc"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae15044026ef19363177d474c6ac890bc">&#9670;&nbsp;</a></span>m_logger_for_blobs</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">flow::log::Logger* ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::m_logger_for_blobs</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">private</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>See ctor. </p>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00183">183</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html">heap_fixed_builder_capnp_msg_builder.hpp</a>.</p>

<p class="reference">Referenced by <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00086">allocateSegment()</a>.</p>

</div>
</div>
<a id="af012d6917cdc16494a22b4b6f2c10edd" name="af012d6917cdc16494a22b4b6f2c10edd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#af012d6917cdc16494a22b4b6f2c10edd">&#9670;&nbsp;</a></span>m_segment_sz</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">const size_t ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::m_segment_sz</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">private</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>See ctor. </p>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00185">185</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html">heap_fixed_builder_capnp_msg_builder.hpp</a>.</p>

<p class="reference">Referenced by <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00086">allocateSegment()</a>.</p>

</div>
</div>
<a id="aad029fd4e08580a785824c48790c748f" name="aad029fd4e08580a785824c48790c748f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aad029fd4e08580a785824c48790c748f">&#9670;&nbsp;</a></span>m_serialization_segments_plus_frame_space</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">std::vector&lt;boost::movelib::unique_ptr&lt;flow::util::Blob&gt; &gt; ipc::transport::struc::Heap_fixed_builder_capnp_message_builder::m_serialization_segments_plus_frame_space</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">private</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Before <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a>, stores each segment allocated as requested by capnp via <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a766736906354f28d6ef2fa0752ba0e21" title="Implements MessageBuilder API.">allocateSegment()</a> <code>virtual</code> API, with <code>.size()</code> equal to <code>.capacity()</code> and &gt;= <code>min_sz</code> (arg to that method); immediately after <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a> each <code>.size()</code> is adjusted to indicate the # of bytes actually used in that segment in the final serialization. </p>
<p >In addition the framing requirements (<a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#ac4e465bb2099093f06cd7e969d2e3de6" title="See ctor.">m_frame_prefix_sz</a> and <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#aa52369c664ada39cedb0a70f08880931" title="See ctor.">m_frame_postfix_sz</a>) are requested. <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder__capnp__message__builder.html#a478c109e008dd33b04b605278c1b2a54" title="Returns pointers to Blobs which are the serialization segments at this time.">emit_segment_blobs()</a> yields an equally sized list of pointers to the <code>.size()</code>-adjusted per-segment <code>Blob</code>s. </p>

<p class="definition">Definition at line <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html#l00199">199</a> of file <a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html">heap_fixed_builder_capnp_msg_builder.hpp</a>.</p>

<p class="reference">Referenced by <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00086">allocateSegment()</a>, <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00042">emit_segment_blobs()</a>, and <a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html#l00135">n_segments()</a>.</p>

</div>
</div>
<hr/>The documentation for this class was generated from the following files:<ul>
<li>transport/struc/<a class="el" href="heap__fixed__builder__capnp__msg__builder_8hpp_source.html">heap_fixed_builder_capnp_msg_builder.hpp</a></li>
<li>transport/struc/<a class="el" href="heap__fixed__builder__capnp__msg__builder_8cpp_source.html">heap_fixed_builder_capnp_msg_builder.cpp</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 11 2025 20:02:27 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
